Apps:Troubleshooting platform security problems
Overview Symbian's Platform Security model introduces the concept of a "capability" - an access token that an executable must have in order to use particular APIs. The capability must be requested by the executable or DLL at build time, and is granted to the application at install time. A Platform Security API policy violation occurs when a process calls an API for which it does not have a required capability or when a process attempts to load a DLL that does not have at least the same capabilities that it has. In most cases the API will return (or Leave) with the error code KErrPermissionDenied (-46). The error may propagate up to the UI in a standard error dialog box (UI dependent). The most common errors associated with capabilities are: *Calling an API when the process/exe has not been granted the required capability *Loading a DLL that does not have all the capabilities of the loading process *Attempting to install an application that cannot be granted the capabilities it requests (e.g. it uses capabilities that can only be granted to Symbian Signed applications when it is self signed) The approach to debugging each of these errors is discussed below. Avoidance The best way to resolve platform security issues is to avoid them in the first place: *Determine what capabilities you need in advance *Ensure that your DLLs have at least the subset of capabilities of all loading processes The techniques below can also be used to work out what capabilities might be missing once you have encountered an error. Determining needed capabilities The easiest way to work out what capabilities you need is to look at the functionality that your application uses and map it to the capabilities (there are only 20 so this is fairly straightforward); In fact, most applications only need one of the 5 user capabilities, and its not much harder if you're using system capabilities. On occasion you may also want to check capabilities against individual APIs - if you're working in Symbian C++ you can do this using the API reference. Note that at time of writing Qt documentation does not include exhaustive capability information. Lastly, the Carbide.c++ capability scanner (see the next section) can pick up a lot of common errors. Notes: *You can specify many capabilities at build time in your MMP file. However if your executable is to be Symbian Signed you will need to justify the requested capabilities. *The requirement for signing does not affect binaries in ROM (or on the Emulated Z drive), so you do not need to worry about "signing" while developing on the Emulator or on a development board where you have built the ROM. *Before finally assigning a capability to process, first assess whether the process should be calling the API in question (at all). There may be an unrestricted higher-level/intrinsically less dangerous API that should be used instead of the capability restricted API. Carbide.c++ capability scanner Carbide comes with a "Capability scanner" plugin that can detect some platform security problems. This is run by selecting the mmp file of a loaded project, right clicking and selecting "Run Capability Scanner on Project MMP". There is no scanner for Qt Creator; the Carbide scanner can be used on the MMP file generated by Qt projects in Carbide.c++. Check DLL dependencies A common error is attempting to load a DLL that does not have every single capability of the loading process. If you have the source you can check the capabilities in the .mmp file (Symbian C++) or the .pro file (Qt). If not, you can check the capabilities of an executable, including .exe and .dll, using the elftran tool. Run the tool using -dump h parameter and check capabilities section. ELFTRAN - ELF file preprocessor V02.01 (Build 564) Copyright © 1996-2006 Symbian Software Ltd. E32ImageFile 'screenshot.exe' Entry points are not called ... Capabilities: 00000000 0001f000 ... The executable in the example above has the capabilities of 0x0001 F000. The definition of these can be found in e32capabilities.h header file, however it is probably easier to use elftran -dump s to get the capabilities of an executable file. ELFTRAN - ELF file preprocessor V02.01 (Build 573) Copyright © 1996-2006 Symbian Software Ltd. E32ImageFile 'HelloWorldBasic.exe' Secure ID: 102ee322 Vendor ID: 10333333 Capabilities: 00000000 000ffffe CommDD PowerMgmt MultimediaDD ReadDeviceData WriteDeviceData DRM TrustedUI ProtServ DiskAdmin NetworkControl AllFiles SwEvent NetworkServices LocalServices ReadUserData WriteUserData Location SurroundingsDD UserEnvironment Platform Security Diagnostics Platform Security Diagnostics ("PlatSecDiagnostics") can be used to determine the required capability. At time of writing Platform diagnostics are only enabled on the Symbian Emulator, or on your own reference hardware. A typical PlatSecDiagnostics error has the following appearance: 151.975 *PlatSec* WARNING - Capability check would have failed - A Message (function number=0x00000000) from Thread Screenshot200005550001::screenshot, sent to Server !Windowserver, was checked by Thread WSERV.EXE10003b200001::Wserv and was found to be missing the capabilities: SwEvent . Additional diagnostic message: Capability check failed for RWindowGroup::CaptureKeyUpsAndDowns API 153.600 *PlatSec* WARNING - Capability check would have failed - A Message (function number=0x00000000) from Thread Screenshot200005550002::screenshot, sent to Server !MsvServer, was checked by Thread !MsvServer1000484b0001::!MsvServer and was found to be missing the capability: ReadUserData. The example shows that the "Screenshot" application is missing two capabilities, i.e. SwEvent and ReadUserData; we can also tell the server that detected the violation, and in the first case, even the API. It's not always possible to determine the API - but we can standard debugging techniques (analysing source, added extra traces to return codes) can be used to work this out if required. Emulator logging PlatSecDiagnostics messages are output to the default output location of RDebug::RPrint() calls. For the Emulator this defaults to the file EPOCWIND.OUT in the windows temp directory. You can use the following command prompt to fetch a copy to your current directory: copy %TEMP%\epocwind.out The Emulator's Platform Security settings are all enabled by default in the epoc.ini file (EPOCROOT/epoc32/data/epoc.ini, where EPOCROOT is the location of the /Epoc32 directory in your SDK installation). The keywords and default attributes to configure PlatSec are shown below: PlatSecDiagnostics ON PlatSecEnforceSysBin ON PlatSecProcessIsolation ON PlatSecEnforcement ON PlatSecDisabledCaps NONE Logging should be enabled by default too. You can check this from the Emulator menu using Tools | Preferences menu - make sure that "Enable Epocwind.out|EPOCWIND.OUT logging" is checked. Alternatively, the log can be enabled from the epoc.ini by setting the value of LogToFile to 1: LogToFile 1 Emulator run time checking In this approach, instead of writing the problem to a log file, the emulator will notify immediately there is a problem. The capability checks can be enabled from the Tools | Preferences menu on the emulator, or by changing the value PlatSecDisabledCaps to NONE in the epoc.ini file. PlatSecDisabledCaps NONE Following this change the emulator will display a dialog each time there is call to a restricted API. Debugging on Device As PlatSecDiagnostics is not enabled on the device, more traditional (read that as slow and frustrating) debugging techniques must be used. A lot of time can be saved by first identifying likely causes of problems - again, the mapping of functionality to capabilities is fairly straightforward, so missing capabilities are likely to be obvious. Summary Thinking about what capabilities protect the functionality you're using, and ensuring that your DLLs have been granted enough capabilities will solve most problems! PlatSecDiagnostics provides the best debug logging of platform security issues, but is only available on the Emulator. Its also possible to use the Carbide.c++ capability scanner to debug common capability related problems.